      Help with NoICE - Debugger for 8 Bit Microprocessors (9-Jun-93)
                (copyright (c) 1992, 1993 by John Hartman)
 
 MOVING AROUND IN HELP:  Use the cursor and PgUp/PgDn keys to move around
 this help file.  Press F1 to search for any character string.  Press ENTER
 or ESC to return to NoICE command mode.


1.  NOICE COMMANDS

 NoICE uses keyboard commands which are generally similar to those of other
 hex monitor programs.  In addition, the function keys provide single-key
 invocation of a number of commands.  Command keywords are case
 insensitive.
 
 Function key commands are executed as a single keystroke.  Other commands
 must be terminated with a carriage return.  Until carriage return is
 pressed, the command may be edited.


2.  INVOKING NOICE

 NoICE assumes an 80286 or better processor running DOS 3.3 or later.  Most
 testing was done on a color VGA display, but EGA and CGA should work as
 well.  Monochrome may work, but I don't have a test machine to try it on.
 NoICE has been successfully run in a DOS window under Microsoft Windows
 (tm).
 
 NoICE is invoked via the command line
 
        NOICExx COMn=baud LINES=mm @cmdfile
 
 where all parameters are optional and order independent.
 
 "COMn" specifies the PC serial port to be used, and may be either COM0,
 COM1, COM2, COM3 or COM4.  "baud" specifies the baud rate, which may be
 any value between 300 and 38400 baud.  Note that the baud rate must match
 that used by the target monitor.  The default if the first parameter is
 omitted is COM1=19200.
 
 "COM0" at any baud rate causes NoICE to simulate the target without any
 communications.  Currently, the simulation is very simple, supporting only
 reading and writing of memory, but not program execution.
 
 The optional LINES parameter specifies the number of lines to be used for
 the display.  Legal values for "mm" are 25, 43, or 50.  The default if
 this parameter is omitted is LINES=25.
 
 The optional SHOW parameter tells NoICE to display in hex all message
 bytes sent to and received from the target.  This is useful when debugging
 a new target monitor.
 
 The final optional parameter specifies a file of NoICE commands to be
 executed after NoICE initializes.  For example, these might be used to
 load the file being debugged, and perhaps to set the address windows or
 insert breakpoints.


3.  COMMAND SUMMARY

 This section lists the commands in alphabetical order.  For more details
 on the operation and parameter format of each command, refer to the
 appropriate sections below.
 
 in each command:
 -      curly brackets {} denote optional parameters.
 -      "addr" denotes an address or address expression
 -      "size" denotes a size or size expression
 -      "value" denotes a numeric expression
 
 @file                  Execute commands from "file"
 B                      Abbreviation of BREAK
 BREAK {addr}           Insert, delete, or display breakpoints
 CHECK addr size        Compute byte checksum on region
 CLEARSYMBOLS           Delete all symbols
 COPY addr1 size addr2  Copy memory from addr1 to addr2
 D                      Abbreviation of DUMP
 DEF                    Abbreviation of DEFINE
 DEFBASE name value     Define base symbol "name"
 DEFB                   Abbreviation of DEFBASE
 DEFINE name value      Define symbol "name"
 DELAY time             Set command delay for command files
 DIR {filespec}         Show file directory in data window
 DOS {command}          Issue DOS command
 DUMP {addr}            Dump block of memory at addr in hex
 ECHO {text string}     Echo "text string" to Data Window
 G                      Abbreviation of GO
 GO {addr}              Begin execution at addr or at PC
 H                      Abbreviation of HELP
 HELP                   Show help display
 I                      Abbreviation of IN
 IN addr                Read byte from port
 INIT addr size value   Initialize memory block at addr to value
 L                      Abbreviation of LOAD
 LOAD file {load offset}        Load Intel or Motorola hex file
 M                      Abbreviation of MEM
 MEM {addr} {val}       Examine/change memory
 N                      Abbreviation of NEXT
 NEXT                   Step over subroutine
 O                      Abbreviation of OUT
 OUT addr val           Write byte to port
 Q                      Abbreviation of QUIT
 QUIT                   Exit to DOS
 RECORD file            Record commands to file
 R                      Abbreviation of REG
 REG {reg val}          Change register
 S                      Abbreviation of STEP
 SET name value         Same as DEFINE
 STEP                   Step into subroutines
 STOP                   Stop recording commands to file
 SYM                    Abbreviation of SYMBOL
 SYMBOL expr            Show symbol with value "expr"
 U                      Abbreviation of UNASM
 UNASM {addr}           Disassemble beginning at addr
 V                      Abbreviation of VIEW
 VAL                    Abbreviation of VALUE
 VALUE expr             Show value of "expr"
 VER                    Show host and target software versions
 VIEW {file}            View file
 
 F1                     Help
 F2                     Dump next block
 F3                     Disassemble next block
 F4                     View file
 F5                     Go
 F6                     List Breakpoints
 F7                     Step
 F8                     Step Over
 F9                     Show Version
 F10                    Quit


4.  COMMAND EDITING

 Function key commands are executed as a single keystroke.  Other commands
 must be terminated with a carriage return.  Until carriage return is
 pressed, the command may be edited.
 
 The left and right cursor keys move the cursor one character to the left
 and right within the current command line.  By pressing the Control key
 along with left and right cursor keys, the cursor may be moved to the
 beginning of words within the current command line.
 
 Printable characters may be inserted at the cursor position by simply
 typing.  Characters to the right of the insertion point will be shifted to
 the right in insert mode, or overwritten in overtype mode.
 
 The Insert key toggles editing between insert (the default) and overtype
 modes.
 
 The Backspace key deletes the character to the left of the cursor, and
 shifts any remaining characters on the line to the left.
 
 The Delete key deletes the character at the cursor position, and shifts
 any remaining characters on the line to the left.
 
 At the command prompt, the up and down cursor keys scroll through a
 command history.  The last 20 commands entered at the keyboard are stored
 in the history list.  Once visible, commands may be edited normally, and
 may be executed by pressing carriage return.  The up and down arrow keys
 are used for other purposes by some other commands, in particular by the
 memory edit and file view commands.  Refer to the descriptions of these
 commands for details.


5.  ENTERING DATA AND ADDRESSES

 Wherever a data value or an address entry is expected, a number, a
 register name, a symbol, or an expression involving numbers, symbols,
 and/or register names may be used.
 
 Numeric data entry is in hex.  Upper or lower case may be used for the
 characters A through F.  Numbers may optionally be prefixed by 0x or 0X
 (i.e., C format).
 
 When a register name is used as a term in an expression, the value
 contained in the register is used as the value of the term.  The legal
 register names will depend on the processor being debugged.  The registers
 names and their current values are displayed in the register window in the
 upper right hand corner of the screen.  Register names are case
 insensitive.
 
 Symbols are defined and given values using the DEFINE (or SET) and DEFBASE
 commands.  When a symbol name is used as a term in an expression, the
 value of the symbol is used as the value of the term.  Symbol names are
 case sensitive.
 
 When used in an expression, a register or symbol name may optionally be
 preceded by a single quote (').  This forces the following characters to
 be evaluated as a register or symbol name, rather than as a number.  This
 allows register names such as "A" or "BC" on the Z80, or symbols such as
 "A1" to be distinguished from hex numbers.  The alternative would have
 been to require a leading zero on hex numbers.  Since numbers are used
 more often than symbols in a typical debug session, this was considered to
 be undesirable.
 
 Valid operators in expressions are addition (+), subtraction (-),
 multiplication (*), integer division (/), logical AND (&), and logical OR
 (|).
 
 Some target processors may support paged memory.  This is primarily
 intended to be used with "Two Bit Memory Management" hardware, as
 discussed in section 17.  However, processors with several address spaces,
 such as the Z8 or 8051 may use paged addresses as well.  If this is the
 case, addresses will be shown as
 
        xx:yyyy
 
 where "xx" denotes the page, and "yyyy" denotes the address within that
 page.  If the processor supports paged memory, then the page may
 optionally be entered as a numeric value, followed by a colon (:), when an
 address is specified.  If no page is specified, then the current page as
 shown in the register window will be used.  If a symbol is specified, the
 page value (if any) of the symbol will be used, unless it is overridden by
 the entry of an explicit page number.


6.  MEMORY COMMANDS



6.1  DUMP memory at address

        DUMP addr
 
 Dumps 128 bytes of data beginning at the specified address.  If no address
 is specified, the next 128 bytes after the previous dump are displayed.
 Data is displayed in both hex and ASCII.
 
 "D" is an abbreviation of "DUMP".  The F2 function key is equivalent to
 "DUMP carriage return".


6.2  MEM: Examine/change memory

        MEM {addr} {val} {val2} {val...}
 
 This command allows the user to examine and/or change individual memory
 locations.
 
 If an address is specified on the command line (with an optional page
 value, if supported), that address will be opened.  Thus
 
        MEM 1000
 
 will display the contents of address 1000, and then wait for user input.
 
 If no address is specified, then the last opened address will be reopened.
 After completion of the previous example, pressing
 
        MEM
 
 will display the contents of address 1000, and then wait for user input.
 
 If one or more data values, separated by spaces, are specified on the
 command line, those values will be written to the one or more successive
 bytes beginning at the specified address:
 
        MEM 1000 55 66 77
 
 will store the value 55 at address 1000, the value 66 at address 1001, and
 77 at the address 1002.  In this case, the original contents of the
 locations will not be shown, and control will return to the NoICE prompt.
 This form of the command is primarily useful when issued from command
 files, but may be used at any time.
 
 Whether or not a data value or values are entered in response to the
 memory prompt, the value of the terminating key determines subsequent
 operation:
 
 CARRIAGE RETURN returns to the main command prompt.
 UP ARROW shows the previous address and its contents.
 DOWN ARROW shows the next address and its contents.
 
 When a data value is written to the target, the target will reread the
 data to verify that the write has succeeded.  If the verify fails, an
 error will be displayed.
 
 "M" is an abbreviation of "MEM".


6.3  UNASM: Disassemble

 This command allows the user to disassemble a program in target memory.
 
 To begin disassembly at "addr" (where "addr" may contain an optional page
 specifier, if supported by the target), enter
 
        UNASM addr
 
 To continue disassembly at the instruction after the last one shown in the
 disassembly window, enter
 
        UNASM
 
 "U" is an abbreviation of "UNASM".  The F3 function key is equivalent to
 "UNASM carriage return".


6.4  LOAD hex file

        LOAD file {load offset}
 
 This command sends the contents of a disk-resident file to the target.
 NoICE supports Motorola "S1" and Intel hex files, and automatically
 determines the file type based on the data in the file.
 
 The optional load offset specifies a paged address which is added to 16
 bit addresses within the load file.  Data is sent to the target locations
 specified by the effective address.  Thus
 
        LOAD file 33:0
 
 will load "file" into page 33, and
 
        LOAD file 1234
 
 will add hex 1234 to all load addresses in "file".
 
 If a Motorola S9 record is encountered, the target program counter will be
 set to the start address contained in the record.
 
 If an Intel type 03 record is encountered, the target program counter will
 be set to the start address contained in the record.
 
 "L" is an abbreviation of "LOAD".


6.5  INIT Initialize memory block

        INIT addr size value
 
 Sets "size" bytes of target memory beginning at "addr" to "value".


6.6  COPY memory block

        COPY addr1 size addr2
 
 Copies "size" bytes of target memory beginning at "addr1" to target memory
 beginning at "addr2".


6.7  CHECK: Compute checksum

        CHECK addr size
 
 Computes and displays the 16 bit sum of "size" bytes of target memory
 beginning at address "addr".


7.  PROCESSOR COMMANDS



7.1  REG: Change register

 Allows the user to change the value of a register shown in the register
 window.
 
        REG reg val
 
 where "reg" is a register name, as shown in the register window, and "val"
 is a value expression.
 
 If no register name or value is specified, then the registers are read
 from the target and the register window is refreshed.  In normal
 operation, this will not change any values in the register window.
 
 "R" is an abbreviation of "REG".


7.2  GO: Begin execution

 Allows the user to begin or continue execution of a target program.
 
        GO addr
 
 will begin execution at "addr" (where "addr" may contain an optional page
 specifier, if supported by the target).
 
 To continue execution at the address indicated by the current program
 counter as shown in the register window, enter
 
        GO
 
 After the GO command is issued, NoICE will wait for the target to execute
 a breakpoint or reset, at which point the target's registers will be
 displayed.  If the target continues execution without encountering a
 breakpoint, the user can force NoICE to return to the command state by
 pressing F10 on the host keyboard.  Since this does not affect the target,
 only commands which do not affect the target should be issued after F10 is
 pressed.  Thus, one can QUIT, or VIEW a file, but cannot DUMP target
 memory.
 
 While the target is executing, if it transmits an ASCII character with a
 value between 0 and 127 decimal, that character will be displayed in the
 NoICE data window as if on a dumb terminal.  The only control characters
 supported are carriage return (0D hex), line feed (0A hex), tab (09 hex),
 bell (07 hex), and backspace (08 hex).  All other characters will be
 displayed using the IBM character set.  NoICE can distinguish displayable
 characters from the breakpoint message because the first byte of all NoICE
 messages is above 128 decimal.
 
 While the target is executing, if the user presses any key other than a
 function or cursor key,  the ASCII representation of the key will be sent
 to the target.  As described above, the F10 key may be used to abort the
 GO command.  All other function and cursor keys are ignored.
 
 This use of the data window allows simple ASCII interaction with the
 running target.  Some of the monitors provide utility subroutines to print
 values in ASCII hex.  Access to such routines may be by software interrupt
 or by direct call.  Consult the source code for your target monitor for
 details.
 
 "G" is an abbreviation of "GO".  The F5 function key is equivalent to "GO
 carriage return".


7.3  STEP into subroutine

        STEP
 
 Allows the user to execute the next instruction of a target program.  If
 the instruction is a call to a subroutine, the subroutine will be entered.
 
 The command operates by placing breakpoints in target memory.  Thus, the
 program must reside in RAM.
 
 In most cases, stepping is virtually instantaneous and NoICE will
 immediately re-enter command mode.  However, in some cases the target may
 not reach the breakpoint.  This may occur, for example, if an interrupt is
 pending when the STEP command is given, and the interrupt handler does not
 return immediately (or at all...).  In such a case, the STEP command will
 behave as if a GO command had been given.  Refer to the GO command for
 details.
 
 The F7 function key is equivalent to "STEP carriage return".


7.4  NEXT: Step over subroutine

        NEXT
 
 Allows the user to execute the next instruction of a target program.  If
 the instruction is a call to a subroutine, the subroutine will be executed
 in its entirety.
 
 The command operates by placing breakpoints in target memory.  Thus, the
 program must reside in RAM.  Subroutine calls which are followed by data
 blocks should not be stepped over, as the breakpoint will be placed
 immediately after the call instruction, on top of the data block.  In such
 cases, the user should place a breakpoint in the appropriate location and
 use the GO command.
 
 In most cases, stepping is virtually instantaneous and NoICE will
 immediately re-enter command mode.  However, in some cases the target may
 not reach the breakpoint.  This may occur, for example, if an interrupt is
 pending when the NEXT command is given, and the interrupt handler does not
 return immediately (or at all...).  The condition may also occur if a
 subroutine being stepped over does not return promptly.  In such cases,
 the NEXT command will behave as if a GO command had been given.  Refer to
 the GO command for details.
 
 The F8 function key is equivalent to "NEXT carriage return".


7.5  BREAK: Breakpoint insert, delete, and display

 Allows the user to insert, delete, and display breakpoints in the target's
 memory.
 
 To insert a breakpoint at "addr" (where "addr" may contain an optional
 page specifier, if supported by the target), enter
 
        BREAK addr
 
 To delete a breakpoint at "addr", enter
 
        BREAK -addr
 
 To delete all breakpoints, enter
 
        BREAK -
 
 To display all breakpoints, enter
 
        BREAK
 
 If a breakpoint location is visible in the disassembly window, a "*"
 character will be shown on the line containing the breakpoint.
 
 When a breakpoint is inserted, the specified location is tested for its
 ability to store the breakpoint instruction, and the original contents are
 then replaced.  When a GO command is issued, all currently set breakpoints
 are inserted before the target is told to commence execution.
 
 "B" is an abbreviation of "BREAK".  The F6 function key is equivalent to
 "BREAK carriage return".


7.6  IN: Read byte from port

        IN addr
 
 Allows the user to perform input from the target port at the address
 specified by "addr".  If the target does not have specific input
 instructions or an I/O address space, then this command simply reads
 target memory at the specified address.
 
 If an address is specified on the command line, that address will be read.
 If no address is specified, then the previously specified address will be
 read.
 
 "I" is an abbreviation of "IN".


7.7  OUT: Write byte to port

        OUT addr val
 
 Allows the user to output "val" to the target port specified by "addr".
 If the target does not have specific input instructions or an I/O address
 space, then this command simply writes to target memory at the specified
 address.  Sixteen address bits are sent to the target, but any page bits
 are ignored.
 
 In contrast with the MEM command, no verification of the write is
 performed after OUT, as this may cause undesired side effects with some
 I/O devices.  Thus, this command may be useful even for processors without
 separate I/O spaces.
 
 "O" is an abbreviation of "OUT".


8.  SYMBOLS



8.1  DEFINE symbol

        DEFINE name value
 
 Defines a symbol called "name" with value "value".  "Name" may contain
 letters, digits, and the special characters underbar (_), period (.),
 dollar sign ($), or question mark (?).  The first character of a name
 cannot be a digit.
 
 "Value" is an expression, which may contain a page number, if supported by
 the target processor.
 
 Symbols may be used by the operator to specify commonly used addresses or
 values, and are displayed by the disassembler when an address, jump
 destination, or instruction argument has a value exactly equal to the
 value of the symbol.
 
 "DEF" is an abbreviation of "DEFINE".
 
 The command alias "SET" is provided for the convenience of users of
 certain Motorola freeware assemblers, which can output symbols to a file
 in the form "SET name hex_value".  The symbols in such a file can be
 defined by "executing" the file using the command
 
        file operator @file.ext.
 
 See section for 12 for information on other forms of automated symbol
 definition.


8.2  DEFBASE: Define base symbol

        DEFBASE name value
 
 Defines a base symbol called "name" with value "value".  "Name" and
 "value" follow the same rules as for symbols.  Base symbols differ from
 standard symbols in that they are used by the disassembler to show
 addresses in the form
 
        BASE+1234
 
 where "BASE" denotes the name of the base symbol whose value is lower than
 and the closest of all other base symbols to the address in question, and
 "1234" is a positive number which denotes the offset from the value of
 BASE.
 
 A common usage of base symbols is to define one for each module of a
 program being debugged.  The value of each base symbol is set equal to the
 address of the first byte of the code segment in the associated module.
 Thus, the disassembly listing will show offsets which match the offsets in
 the assembly listing file for the module.
 
 "DEFB" is an abbreviation of "DEFBASE".
 
 See section for 12 for information on automated symbol definition.


8.3  CLEARSYMBOLS: Delete all symbols

        CLEARSYMBOLS
 
 Deletes any symbols defined in this debug session.  Exiting and re-
 entering NoICE will do the same, but the command is provided for
 completeness.


8.4  SYMBOL: Show symbol with value "expr"

        SYMBOL {expr}
 
 This command displays the symbol whose value represents the expression.
 If the value exactly matches a symbol, the name of the symbol will be
 shown.  If there is no exact match, but a base symbol whose value is lower
 than the expression exists, the name of the base symbol and the offset
 from it to the value of the expression will be shown.  If no appropriate
 symbol or base symbol is found, the message "no symbol found" will be
 shown.
 
 If no expression is specified, the names and values of all defined symbols
 and base symbols will be shown.
 
 "SYM" is an abbreviation of "SYMBOL".


9.  COMMAND FILES



9.1  @file: Execute commands from file

        @file.ext
 
 This command may be used to execute a list of commands contained in a text
 file "file.ext".  Only commands invoked by printable ASCII characters at
 the NoICE main prompt will be executed completely.  Thus, for example, the
 command
 
        M 1000 55 66 77
 
 will store the value 55 at address 1000, the value 66 at address 1001, and
 77 at the address 1002.  On the other hand, the command
 
        M 1000
 
 will display the contents of address 1000, and then wait for user input -
 not the next line of the command file.  Only when the user presses the
 ENTER key to terminate the M command will additional commands be fetched
 from the command file.
 
 Command files may be nested up to three deep.  If the command
 
        @file2
 
 appears in command file1, the effect is to call the commands in file2.
 When the last command in file2 is executed, control will return to file1.
 
 If an error occurs in the execution of a command from a command file, all
 open command files will be closed and execution of commands will cease.


9.2  RECORD commands to file

        RECORD file.ext
 
 This command records commands entered at the command prompt in the
 specified file.  If the file already exists, it is deleted and a new file
 of the same name is created.  Recording continues until the STOP command
 is entered.  Because only commands entered at the command prompt are
 recorded, keystrokes entered in the file viewer, or when editing commands
 are not recorded.
 
 Recorded files will most often be played back as command files, using the
 @file command.


9.3  STOP recording commands to file

        STOP
 
 This command closes the current recording file, if one is open.  If no
 recording file is open, this command has no effect.


9.4  ECHO text string to Data Window

        ECHO {string}
 
 Shows the remainder of the command line in the data window.  This is
 primarily useful within command files (@file) in order to annotate
 actions.  If no string is specified, a blank line will be displayed.


9.5  DELAY: Set post-command delay

        DELAY time
 
 Specifies a time delay for use after each command from a command file.
 This slows down command execution so that an operator can view the
 results.  The time delay is specified as a decimal number of DOS ticks
 (18.2 ticks per second).  Specifying a time delay of zero disables the
 delay.  Pressing any key during a delay interval aborts the delay.  This
 is useful if you accidentally set the delay to something huge.


10.  MISCELLANEOUS COMMANDS



10.1  HELP: Show help display

        HELP
 
 Opens a file containing help information and displays it in the View
 window.  The file contains a description of available commands and their
 syntax, derived from this document.
 
 "H" is an abbreviation of "HELP".  The F1 function key is equivalent to
 "HELP carriage return".


10.2  QUIT: Exit to DOS

        QUIT
 
 Exits NoICE and returns to DOS.
 
 "Q" is an abbreviation of "QUIT".  The F10 function key is equivalent to
 "QUIT carriage return".


10.3  VALUE: Show value of expression

        VALUE expr
 
 This command displays the value of the expression "expr" in hex and in
 decimal.  One use of this is do perform hex to decimal conversion, or hex
 arithmetic.
 
 Since any NoICE expression can contain symbol or register names, this
 command may also be used to show the value of a symbol.
 
 "VAL" is an abbreviation of "VALUE".


10.4  VIEW file

        VIEW file.ext
 
 This command is used to view a file in the command window.  If no file
 name is specified, then the last viewed file (if any) is viewed.  Once the
 VIEW command has been executed, NoICE will remain in view mode until
 either the ESC or ENTER key is pressed.
 
 While in view mode, several keys have special functions.  The menu line at
 the bottom of the screen changes to reflect these functions.
 
 The up and down cursor keys move the display back and forward in the file
 by one line.
 
 The page up and page down keys move the display back and forward in the
 file by one window of lines.
 
 The left and right cursor keys scroll the display left and right by eight
 characters.  This is useful to view listing files, or other files wider
 than the width of the display window.  Lines longer than 300 bytes will be
 truncated at 300 bytes.
 
 The Home key moves the display to the beginning of the file.
 
 The End key moves the display to the end of the file.
 
 The F1 key prompts the user for a search string.  The file is then
 searched from the current position for a match to the entered string.  If
 the string is found, it is displayed on the top line of the window, along
 with the succeeding page of the file.
 
 The F2 key repeats the previous search, beginning at the current position
 in the file.
 
 The F3 key toggles the display between ASCII and hex dump.  When in hex
 mode, the search function searches the file data as displayed in the
 viewer.  "Search" and "End" operations in hex mode may be rather slow.
 
 "V" is an abbreviation of "VIEW".  The F4 function key is equivalent to
 "VIEW carriage return".
 
 +---------------------------------------------------------------+
 |RESET        F3        DI                   | A  56    0000 AF'|
 |0086         AF        XOR    A,A           | BC 0000  0000 BC'|
 |0087         01EE00    LD     BC,SCRP_REG   | DE 0000  0000 DE'|
 |008A         ED79      OUT    (C),A         | HL 1234  0000 HL'|
 |008C         3E1C      LD     A,1C          | IX 0000    00 I  |
 |008E         01EF00    LD     BC,SCDP_REG   | IY 0000     0 IFF|
 |0091         ED79      OUT    (C),A         | SP 1000          |
 |INIT         31800A    LD     SP,TASK_REGS  | PC 0085          |
 |0096         216103    LD     HL,INIOUT     | FL .Z.H..NC      |
 |0099         1616      LD     D,16          | PG  00           |
 |009B         0600      LD     B,00          |                  |
 |rst10        4E        LD     C,(HL)        |                  |
 |009E         23        INC    HL            | (RESET)          |
 |----------- File monz80.l Line 336 ----------------------------|
 |               333                                             |
 |0085 f3        334      die                      ;no interrupts |
 |0086 af        335      xor     a,a             ;access to wait|
 |0087 01ee00    336      ld      bc,SCRP_REG                    |
 |008a ed79      337      out     (c),a           ;set pointer to|
 |008c 3e1c      338      ld      a,00011100b                    |
 |               339      ;         00            ;no wait for in|
 |               340      ;           0           ;no wait for in|
 |               341      ;            1          ;one extra wait|
 |>v                                                             |
 |HOME=top END=end F1=find F2=find next F3=hex  ENTER or F10=exit|
 +---------------------------------------------------------------+
 
 Figure 10-4  NoICE Screen Showing File Viewer


10.5  VER: Display host and target versions

        VER
 
 Displays the software version number and other information for both the PC
 host and for the remote target.
 
 If the processor type of the remote target does not match that expected by
 NoICE, an error will be displayed.  If there is a mismatch, the register
 and execution commands will be locked out.  Memory manipulation commands,
 such as MEM, DUMP, UNASM, LOAD, and all other NoICE commands will function
 properly regardless of target type.
 
 The F9 function key is equivalent to "VER carriage return".


10.6  DIR: Display file directory

        DIR {filespec}
 
 A DOS DIR command is issued with the specified filespec (if any), and with
 output redirected to the file NOICE.TMP in the current directory.
 NOICE.TMP is then opened by the file viewer.
10.7  DOS: Issue DOS command

        DOS {command}
 
 The specified command is issued to DOS using the C "system" function.  A
 new copy of COMMAND.COM is loaded, but NoICE is not swapped out.  Thus,
 the amount of memory available to the command may be limited.  (This is a
 hex debugger, not a programming environment!)
 
 When the DOS command completes, or when the invoked program exits, the
 user is prompted to "press any key" to return to NoICE.  When a key is
 pressed, the NoICE disassembly and register windows are repainted, but the
 area of the data window is left unchanged.


11.  ERROR MESSAGES

 If the syntax of a command is incorrect, or if an error occurs during the
 execution of a command, an error will be displayed.  The possible errors
 are listed below, along with possible reasons for their occurrences.
 
 BAD DATA IN FILE:  the specified file for LOAD contains data inconsistent
 with the assumed file format.
 
 BAD RESPONSE FROM TARGET:  the target has responded to a request with an
 incorrect response.  This may indicate that the target has unexpectedly
 been reset, or is otherwise confused.
 
 BREAKPOINT OVERLAPS ANOTHER:  an attempt was made to insert a multiple
 byte breakpoint one or more bytes of which would overlap the region where
 a breakpoint already exists.
 
 COMMUNICATIONS ERROR:  some communications error has occurred.  This may
 indicate an incorrect baud rate, or connection to a serial device other
 than a NoICE target.
 
 DUPLICATE BREAKPOINT:  an attempt was made to insert a breakpoint where
 one already exists.
 
 EXPRESSION MISSING:  a required expression was not specified.  A common
 reason is the entry of a hex number without a leading digit, for example
 "AA" rather than "0AA"
 
 FATAL ERROR:  some error has occurred which terminates NoICE.
 
 ILLEGAL PAGE:  the specified page is not legal for this target processor.
 
 ILLEGAL PAGED ADDRESS:  the specified address offset is outside the range
 allowed by the target for paged addresses.
 
 INVALID REGISTER:  the specified register name is unknown to this target
 processor.
 
 NO BREAKPOINT STORAGE:  an attempt was made to insert a breakpoint for
 which insufficient local storage exists.
 
 NO FILE SPECIFIED:  no file name was specified for the LOAD command.
 
 NO RESPONSE FROM TARGET:  a timeout has occurred during communications
 withe the target.  This may indicate that the target has locked up, or an
 incorrect port or baud rate was specified for NoICE.
 
 NO SUCH BREAKPOINT:  an attempt was made to delete a breakpoint where none
 exists.
 
 NO SUCH FILE:  the specified file does not exist in the specified
 directory (or current directory, if none is specified).
 
 OPERAND MISSING:  an operator was not followed by an operand or
 expression.
 
 OPERATOR MISSING:  an expected operator was not specified.  Will occur if
 two numeric values are specified without a valid operator between them.
 
 OPERATION ABORTED:  the user has aborted a command, such as GO, by
 pressing Control-Break.
 
 TARGET TYPE MISMATCH:  the command has been aborted because the target is
 of a different type than expected by this NOICExx.EXE.  NoICE asks the
 target for type information as part of its initialization, and when the
 VER command is invoked.  If the target responds incorrectly to this poll,
 or does not respond to it, then NoICE will issue this error when a
 processor-specific command such as GO or REG is attempted.  This may occur
 if the target is powered off when NoICE is started.  In this case, turn
 the target on and either exit and re-enter NoICE, or use VER (F9) to poll
 the target.
 
 TARGET WRITE FAILURE:  verification of a target write indicates that the
 write was not successful.  Perhaps the specified address is not RAM, or is
 an I/O device.
 
 UNEXPECTED FUNCTION KEY:  an unrecognized function key was pressed.
 
 UNKNOWN COMMAND:  an unrecognized command was entered.
 
 UNKNOWN FILE FORMAT:  the specified file for LOAD is not in a known
 format.
 
 UNKNOWN OPERATOR:  an operator unknown to NoICE was specified.
12.  GENERATING SYMBOL FILES

 The use of NoICE symbols can make debugging significantly easier.  If
 there are only a few symbols to define, this may be done by hand, perhaps
 while viewing the link map and/or assembly listing file to determine
 symbol values.  For large-scale use, however, it is useful to generate the
 symbols automatically during the assembly and linking process.
 
 While NoICE itself could have been taught to load symbols in a variety of
 formats, this would make the program larger, and would restrict the number
 of formats supported.  Thus, the approach taken was to write small utility
 programs which process the output of various cross assemblers and linkers.
 The output of this processing is a NoICE command containing DEF (define)
 commands for the symbols to be defined.  The command file may then be
 interpreted by NoICE to define the symbols.  Thus, symbols from a new
 assembler or linker may be supported simply by writing the appropriate
 symbol processing utility.
 
 The NoICE package includes symbol processing utilities to perform this
 function for a number of popular assemblers.  The source code for these
 utilities is provided, as examples if you need to customize them, or write
 a similar utility for use with another assembler.  Unlike the remainder of
 NoICE, these utilities are public domain, and may be copied and modified
 at will for any non-commercial purposes.


12.1  AVOSYM:  Avocet AVMAC

 Avocet (tm) makes a line of cross assemblers which targets most 8 bit
 microprocessors.  All share the same AVLINK linker.  A linker switch (-SY)
 controls the production of a symbol file.
 
 AVOSYM.EXE converts the AVLINK symbol file (not the map file) into a
 command file which DEFines the symbols.  Command line is:
 
        AVOSYM infile outfile
 
 where "infile" represents the symbol file output by AVLINK, and "outfile"
 represents the output command file.  If "outfile" already exists, the old
 file will be deleted and replaced by the new one.  AVLINK symbol files
 normally have the extension ".SYM".


12.2  BSOSYM:  BSO/Tasking

 BSO/Tasking (tm) makes a line of cross assemblers which targets most 8 bit
 microprocessors.  All share the same MLINK linker.  A linker switch
 controls the production of a map file, and specifies whether the map file
 should include only global symbols, or both global and local symbols.  In
 order to include local symbols, the module or modules for which the
 symbols are desired must be assembled with the appropriate switch to
 include local symbol information in the object file.
 
 BSOSYM.EXE converts the MLINK map file into a command file which DEFines
 the symbols.  Command line is:
 
        BSOSYM infile outfile
 
 where "infile" represents the map file output by MLINK, and "outfile"
 represents the output command file.  If "outfile" already exists, the old
 file will be deleted and replaced by the new one.  MLINK map files
 normally have the extension ".MAP".


12.3  MOTSYM:  Motorola Freeware

 Motorola (tm) offers a set of free assemblers for most of their
 microprocessor line.  These are not macro assemblers, and the output is
 not relocatable, but the price is right.  They are available on the
 Motorola Freeware BBS, and on various other BBS.  Of interest to NoICE
 users are AS9 for the 6809, and AS11 for the 68HC11.
 
 MOTSYM.EXE converts the symbol table or cross reference portion of a list
 file produced by ASxx into a command file which DEFines the symbols.  The
 command line to assemble and produce a suitable list file is:
 
        ASxx sourcefile -l s >listfile
 
 The command line to process the list file is:
 
        MOTSYM listfile outfile
 
 where "listfile" represents the list file output by ASxx, and "outfile"
 represents the output command file.  If "outfile" already exists, the old
 file will be deleted and replaced by the new one.


12.4  SAMSYM:  PseudoSam

 PseudoCode corporation offers a set of PseudoSam assemblers for a variety
 of microprocessor.  Shareware and commercial versions are available, with
 various capabilities.
 
 SAMSYM.EXE converts the symbol table or cross reference portion of a list
 file produced by PseudoSam Axx into a command file which DEFines the
 symbols.
 
 The command line to process the list file is:
 
        SAMSYM listfile outfile
 
 where "listfile" represents the list file output by Axx, and "outfile"
 represents the output command file.  If "outfile" already exists, the old
 file will be deleted and replaced by the new one.
12.5  Z800SYM:  Zilog ASM800

 Zilog (tm) includes a cross assembler for the Z8, Z80, Z180, and Z800 with
 various evaluation boards which they sell.  Also included are a number of
 object file processing utilities, including MNM which generates symbol
 listings.  Switches specify the listing format, and whether the symbol
 file should include only global symbols, or all symbols.
 
 Z800SYM.EXE converts the MNM symbol file into a command file which DEFines
 the symbols.  Command lines are:
 
        MNM -o symfile file.lnk
 
 where "file.lnk" is the MUFOM format output from the linker, and "-o
 symfile" specifies that the output should be directed to "symfile".  The
 "-l" switch specifies that local symbols should be included.
 
        Z800SYM symfile outfile
 
 where "symfile" represents the symbol file output by MNM, and "outfile"
 represents the output command file.  If "outfile" already exists, the old
 file will be deleted and replaced by the new one.


13.  PROCESSOR SPECIFIC DATA

 As of the date of this document, NoICE supports the following processors:


13.1  Zilog Z80, Z85C1X, Z180 Family

 In addition to the basic Z80 instruction set, the enhanced instructions
 for the Z85C1X and Z180 family are supported.  Because of this, the
 disassembler may show instructions which are not compatible with a given
 target.  For example, the IN0 instruction of the Z180 does not exist on
 the Z80 or Z85C1X.  While the instruction will be disassembled, operation
 of single-step is not guaranteed for instructions not supported by a given
 target.
 
 Registers supported are A, FL, AF, B, C, D, E, H, L, BC, DE, HL, IX, IY,
 SP, PC, I, IFF, A', FL', AF', B', C', D', E', H', L', BC', DE', HL', and
 PG if paged memory is used.
 
 The monitor is less than 1024 bytes in length, including I/O
 initialization, and uses approximately 256 byte of RAM.  The monitor has
 been assembled with the Zilog ASM80 assembler shipped with Zilog
 evaluation boards.  Other assemblers may be used if the appropriate
 changes are made to pseudo-ops and source file formatting.
13.2  Zilog Z8 Family

 This processor has three separate address spaces: register, code, and
 external.  The target uses the LDC or LDE instructions to read and write
 code or external memory.  Thus, the target must support either the
 instructions LDC R,@RR; LDC @RR,R; LDCI @R,@RR; and LDCI @RR,@R, or the
 LDE equivalents, and the hardware must be designed appropriately.  The
 Zilog Z86C95 evaluation board is so constructed.
 
 For simplicity at the PC host, addresses are specified by the user as if
 there were a single 16 bit address space:  Addresses below 0100 hex are
 regarded as specifying registers.
 
 Addresses between 0100 and 04FF hex are regarded as specifying Expanded
 Register File registers, with the ERF set selected by address bits 9-8,
 (ERF sets A through D), the register bank selected by bits 7-4, and the
 register by bits 3-0.
 
 Addresses 500 hex and above access code memory.  The low 500 hex bytes of
 code memory are not accessible via the serial link.  This is not regarded
 as a problem, as this region will typically be where the target monitor
 resides.
 
 If support for external memory as distinct from code memory is desired, it
 may be implemented by using memory pages.  For example, the paged region
 could be specified as 0000 to 0ffff hex; with page 0 being register
 memory, page 1 code memory, and page 2 external memory.  Suitable
 modifications of the target monitor would be required, but no changes are
 required to NOICEZ8.
 
 Registers supported are R0 through R15, FL, SP (16 bits), PC, RP, and PG
 if paged memory is used.
 
 The target monitor uses a set of 16 registers, which may not be used by
 the application code.  By appropriate modification of the monitor source
 code, the user may select which set of registers is used.
 
 The Z8 unfortunately has no single-byte op-code suitable for use as a
 breakpoint instruction.  Thus, NoICE uses a two byte "CALL @reg" (hex
 0D4h) instruction.  This has two effects.  First, if the application code
 modifies the register pair containing the call address (R0 and R1 of the
 monitor's register set), then breakpoint or single-step is likely to jump
 somewhere more exciting than the monitor's breakpoint entry.  Secondly,
 breakpoints cannot be placed on successive bytes, as the inserted
 breakpoint instructions would overlap.  NoICE will prevent the insertion
 of a breakpoint which would overlap another.
 
 The monitor has been assembled with the Zilog ASM8 assembler shipped with
 Zilog evaluation boards.  Other assemblers may be used if the appropriate
 changes are made to pseudo-ops and source file formatting.
13.3  Motorola 68HC11 Family

 Registers supported are A, B, X, Y, SP, PC, CC, and PG (if paged memory).
 
 Interrupts for RESET, CLOCK FAIL, COP, ILLEGAL OP-CODE, SWI and XIRQ enter
 the monitor and report a processor state which names the interrupt.  All
 other interrupts are routed through RAM vectors which are initialized to
 enter the monitor and report a processor state which names the interrupt.
 If user code changes the contents of a RAM vector, that interrupt will be
 passed to the user-specified routine without entering the monitor.  While
 SWI is preferred for use as a breakpoint instruction, JSR may be used with
 appropriate modification of the target monitor.
 
 The monitor is approximately 1300 bytes in length, and uses approximately
 256 byte of RAM.  The monitor has been assembled with the AS11 assembler
 available from Motorola's Freeware BBS.  Other assemblers may be used if
 the appropriate changes are made to pseudo-ops and source file formatting.
 The monitor must be modified in order to assemble with Dunfield's XASM, as
 XASM does not allow symbols longer than 10 characters.


13.4  Motorola 6809

 Registers supported are A, B, X, Y, U, SP, PC, CC, and PG (if paged
 memory).
 
 Except for RESET and SWI, interrupts are routed through RAM vectors which
 are initialized to enter the monitor and report a processor state which
 names the interrupt.  If user code changes the contents of a RAM vector,
 that interrupt will be passed to the user-specified routine without
 entering the monitor.  While SWI is preferred for use as a breakpoint
 instruction, SWI2 or SWI3 may be used with appropriate modification of the
 target monitor.
 
 Unique processor states are reported for
    -   RESET
    -   BREAKPOINT (SWI)
    -   NMI  (may be routed through RAM vector rather than monitor)
    -   IRQ  (may be routed through RAM vector rather than monitor)
    -   FIRQ  (may be routed through RAM vector rather than monitor)
    -   SWI2  (may be routed through RAM vector rather than monitor)
    -   SWI3  (may be routed through RAM vector rather than monitor)
 
 The initial handler for FIRQ will push all processor registers if they are
 not pushed by the interrupt.  The "E" bit of the stacked processor status
 register is set so that RTI will act appropriately.
 
 The 6809 contains a wide variety of instructions which can affect the
 program counter.  The single-step function supports many, but not all, of
 these.  Unsupported are
        TFR     rr,PC
        XFR     rr,PC
        XFR     PC,rr
 
 If the user attempts to step these instructions, a breakpoint will be
 inserted after the instruction, but not at the location specified by
 register "rr".
 
 The following instructions ARE supported for single-step
        PULS    PC,...
        PULU    PC,...
        JMP     all address modes
        JSR     all address modes
 
 The monitor is less than 1024 bytes in length.  The monitor has been
 assembled with the AS9 assembler available from Motorola's Freeware BBS.
 Other assemblers may be used if the appropriate changes are made to
 pseudo-ops and source file formatting.  The monitor must be modified in
 order to assemble with Dunfield's XASM, as XASM does not allow symbols
 longer than 10 characters.


13.5  6502, 65C02 Family

 Registers supported are A, CC, X, Y, SP, PC, and PG if paged memory is
 used.
 
 The monitor is less than 1024 bytes in length, including I/O
 initialization.  The monitor uses approximately 256 bytes of RAM, but
 requires no page 0 RAM.  The monitor has been assembled with the Avocet
 AVMAC (tm) assembler.  Other assemblers may be used if the appropriate
 changes are made to pseudo-ops and source file formatting.


13.6  Mitsubishi M50740 Family

 The Mitsubishi M50740 family processors are similar, but not identical, to
 the 65x02 family.  In particular, several of the bit set, clear, and
 branch instructions have different op-code values between the two
 processors.  While constructing a 65x02 version would be an easy task, the
 M50740 version is not suitable for use with the 65x02 in its current form.
 
 Registers supported are A, CC, X, Y, SP, PC, and PG if paged memory is
 used.
 
 The monitor is less than 1024 bytes in length, including I/O
 initialization.  The monitor uses approximately 256 bytes of RAM, but
 requires no page 0 RAM.  The monitor has been assembled with the Avocet
 AVMAC (tm) assembler.  Other assemblers may be used if the appropriate
 changes are made to pseudo-ops and source file formatting.


13.7  Other Processors

 Additional processors may be supported in the future, as time and interest
 allow.  Some likely candidates are listed below.  If you are interested in
 one of these, or wish to suggest another target, please contact the author
 at the address listed in the final section of this document.
 
 The 8051 is probably the next processor to be implemented.  Like the Z8,
 the 8051 has three address spaces:  register, data, and code.  As with the
 Z8, the addressing of these spaces is up to the target.  Three separate
 spaces could be maintained by using paging.  A simple method would be to
 map everything into a single 16-bit space:  addresses 0000 to 00FF for
 register memory, and addresses 0100 to FFFF for code/data memory.  The
 hardware would need to combine RD with PSEN.  This is done on many 8051
 evaluation boards.
 
 The 6805 would be an easy port from the 6502 version.  The main problem is
 that there doesn't seem to be a version of the 6805 which supports
 external RAM into which code can be loaded.  Some versions contain a fair
 amount of on-chip EEPROM, but this is not suitable for single-step
 operation via breakpoints.  If anyone knows of an appropriate evaluation
 version, please contact the author.
 
 The Hitachi H8 family looks straightforward, but I don't have a cross
 assembler or any target hardware on which to check out a monitor.


14.  HOW IT WORKS

 NoICE relies on a target monitor which implements a small set of commands;
 and a PC-resident host program which does most of the work.  Commands are
 provided to read target configuration, to read and write blocks of memory,
 to read and write processor registers, to input from and output to I/O
 ports, to set and clear breakpoints, and to execute.  Everything else is
 done by the PC.
 
 The commands are identical in format for all target processors.  Only the
 format of the register block is unique to the specific target processor.


14.1  Breakpoints, Execution, and Single-Step

 One of the unique features of NoICE is that it is able to implement
 single-step operation without the use of special hardware.  This is
 accomplished by the insertion of breakpoint instructions at the
 location(s) to be executed after the instruction to be stepped.  For most
 instructions, the next instruction to be executed is the next one in
 sequential memory.  Since the disassembler knows how long each instruction
 is, the address of the next sequential instruction may be obtained simply
 by calling the instruction processing function for the instruction to be
 stepped.  A breakpoint is inserted at the next sequential address, and the
 target told to execute until the breakpoint is hit, at which time the
 breakpoint is removed.
 
 Certain instructions, such as branches, jumps, subroutine calls, and
 returns may cause the flow of execution to be changed.  Code is added to
 the instruction processing functions of such instructions to derive the
 alternate execution address.  In the case of subroutine returns and
 computed jumps, this may necessitate reading target registers or memory.
 Breakpoints are inserted at both the alternate execution address and the
 next sequential address, and the target told to execute until the
 breakpoint is hit, at which time the breakpoint is removed.
 
 We had originally planned to determine the single next instruction
 address, but this caused several difficulties:  the first is the larger
 number of instruction processing functions which must be written, to
 account for different conditional branches and the like.  A more serious
 problem exists for targets such as the Mitsubishi M50740 family which can
 branch based on the states of bits in I/O devices:  For such instructions,
 there is no guarantee that the same value will be seen by the monitor
 reading ahead, and by the target at execution time.  For these reasons, we
 insert two breakpoint instructions for all transfer of control
 instructions.


15.  TARGET COMMUNICATIONS

 NoICE relies on a target monitor which implements a small set of commands;
 and a PC-resident host program which does most of the work.  Commands are
 provided to read target configuration, to read and write blocks of memory,
 to read and write processor registers, to input from and output to I/O
 ports, to set and clear breakpoints, and to execute.  Everything else is
 done by the PC.
 
 The commands are identical in format for all target processors.  Only the
 format of the register block is unique.  The commands are described below.
 
 NoICE can use any of COM1, COM2, COM3, or COM4 serial ports at any baud
 rate from 300 to 38400.  57600 baud may work if both your PC and your
 target are fast enough.  Non-standard baud rates (that is, rate not a
 power of two multiple of 300) are supported by the PC:  the baud rate
 divider is calculated from the entered baud rate.
 
 Any PC asynchronous card using an 8250 or 16450 UART may be used.  Most
 common will be RS-232, but RS-422 or RS-485 is also possible as long as
 the card looks to the processor like a standard COM card.  NoICE turns RTS
 on before sending a message, and turns RTS off at all other times.  This
 is intended to allow the use of half duplex communications devices, such
 as short-haul modems, or single wire-pair RS-485.  PC-compatible RS-485
 cards and RS-232 to RS-485 convertors are available from Black Box, JDR, B
 and B, and various other vendors.
 
 RTS will remain off during target execution.  As described in section 7.2,
 operator keyhits will be output to the UART by NoICE during target
 execution.  However, since RTS will remain off, these characters may not
 be seen by the target if a hslf-duplex communications device or medium is
 being used.
 
 The message format is
 
    Byte 0
        Function code, whose value must be greater than 80 hex or target
        will ignore it.  This aids in re-synchronization if target and host
        lose sync.
    
    Byte 1
        Length of data to follow, 0 to 255.  Certain target implementations
        may restrict the length to a smaller value.  All targets must allow
        a data length of at least 32.
    
    Byte 2 to n
        Data (if Byte 1 is non-zero).  Interpretation of the data is
        determined by the function code in Byte 0.  See below.
    
    Byte n+1
        Two's complement of the eight bit sum of Bytes 0 through n, such
        that the sum of Bytes 0 through n+1 is zero for a correctly
        received message.  Messages with an incorrect checksum are ignored.
 
 The communications protocol is half duplex, with the PC acting as master.
 Messages receive an immediate reply, except for FN_RUN_TARGET, the reply
 to which will be generated if and when the target executes a breakpoint.


15.1  FN_GET_STATUS (0FFH) get device info

 This function allows the host to identify the target's processor type, and
 to obtain other useful information about the target.
 
 The request contains no data byte.  The reply data is as follows:
 
    Byte 2
        Processor type
    
    Byte 3
        Size of target comm buffer (32 to 255)
    
    Byte 4
        Options.  Currently zero.
    
    Bytes 5,6
        Low bound of target mapped memory (0 if not mapped).  Least
        significant byte first.
    
    Bytes 7,8
        High bound of target mapped memory (0 if not mapped) Least
        significant byte first.
    
    Byte 9
        Length of target's breakpoint instruction
    
    Bytes 10 to n
        Target's breakpoint instruction (number of bytes specified by the
        value of Byte 9)
    
    Bytes n+1 to m
        Zero-terminated ASCII string:  target description


15.2  FN_READ_MEM (0FEH) read memory

 This function allows the host to read bytes from the target's memory.  The
 request data is always 4 bytes long, and appears as follows:
 
    Byte 2
        Memory page (or zero if paged memory is not supported)
    
    Bytes 3,4
        Memory address, least significant byte first
    
    Byte 5
        Number of bytes to return
 
 The reply data is as follows:
 
    Bytes 2 to n
        Requested data bytes


15.3  FN_WRITE_MEM (0FDH) write memory

 This function allows the host to write bytes to the target's memory.
 
 The request data is always at least 3 bytes long, and appears as follows:
 
    Byte 2
        Memory page (or zero if paged memory is not supported)
    
    Bytes 3,4
        Memory address, least significant byte first
    
    Bytes 5 to nn
        Data to write.  The length of the data to write may be computed
        from the net data length in Byte 1 as write length = Byte 1 - 3
 
 The reply data is as follows:
 
    Byte 2
        Status value for write: 0=success, 1=failed verify after write


15.4  FN_READ_REGS (0FCH) read registers

 This function allows the host to read the target processor's registers.
 
 The request contains no data bytes.  The reply data is as follows:
 
    Byte 2 to nn
        Register image.  The byte order must match the target register
        definition in the host's target support module.  Any multi-byte
        values must be provided least significant byte first.


15.5  FN_WRITE_REGS (0FBH) write registers

 This function allows the host to write the target processor's registers.
 
 The request data is as follows:
 
    Byte 2 to nn
        Register image.
 
 The reply data is as follows:
 
    Byte 2
        Status value for write: 0=success, 1=failed write


15.6  FN_RUN_TARGET (0FAH) run target

 This function tells the target to begin execution at the address specified
 in its local register structure.  If the host wishes to specify an
 execution address, it must do so by writing to the target's registers
 before issuing the execute command.
 
 The request contains no data byte.
 
 The reply data is as follows (returned when and if the target executes a
 breakpoint or is reset):
 
    Byte 2 to nn
        Register image.


15.7  FN_SET_BYTES (0F9H) breakpoint

 This function allows the host to write to target memory, and to obtain the
 contents before the write.  It is used to insert and remove breakpoint
 instructions.
 
 The length of the request is four times the number of bytes to be set.
 Request data is as follows:
 
    Byte 2
        Page for first byte (0 if paged memory not supported)
    
    Bytes 3,4
        Address for first byte (least significant byte first)
    
    Byte 5
        Data to store at first byte
    
        ...
    
    Byte n
        Page for n'th byte (0 if paged memory not supported)
    
    Bytes n+1,n+2
        Address for n'th byte (least significant byte first)
    
    Byte n+3
        Data to store at n'th byte
 
 The reply data is as follows:
 
    Byte 2
        Data from first byte before store
    
        ...
    
    Byte n+2
        Data from n'th byte before store
 
 If the target is unable to successfully write a byte (for example, if an
 attempt is made to write a breakpoint into ROM), no further insertions
 will made in response to the command, and the returned data will include
 only the number of bytes actually inserted.  Thus, the return length may
 be used to verify complete insertion of all bytes, or to tell where a
 failure has occurred.


15.8  FN_IN (0F8H) input from port

 This function allows the host to read a target input port.  If the target
 processor does not support separate memory and input/output spaces, then
 this command reads a byte from target memory.
 
 The request data is as follows:
 
    Bytes 2,3
        Port address, least significant byte first
 
 The reply data is as follows:
 
    Byte 2
         Data byte from port
15.9  FN_OUT (0F7H) output to port

 This function allows the host to write to a target output port.  If the
 target processor does not support separate memory and input/output spaces,
 then this command writes a byte to target memory.  Note that unlike
 FN_WRITE_MEM, no verification is done, since re-reading an I/O device may
 cause undesired operation.  For this reason, this function is useful even
 for processors without separate input/output address spaces.
 
 The request data is as follows:
 
    Bytes 2,3
        Port address, least significant byte first
    
    Byte 4
        Data byte to write
 
 The reply data is as follows:
 
    Byte 2
        Status value: 0


15.10  FN_ERROR (0F0H) error reply

 This function is never sent by the host to the target.  It may be returned
 by the target in response to a message with a valid checksum, but whose
 function code is unknown to the target.
 
 The reply contains no data byte.


16.  CUSTOMIZING A TARGET MONITOR

 If your target processor is one of those currently supported by NoICE, the
 task of supporting a new target hardware platform is relatively easy.  The
 starting point is the existing basic target monitor for your processor.
 
 The target monitors are written such that hardware-dependent code is
 isolated to a few locations in the source file.  The areas to be examined
 and changed as required are these:
 
 1)  Target monitor ROM location, ROM_START.  This will depend on where the
 processor begins execution, on the memory technology being used, and
 possibly on requirements for other ROM-resident code.  If a ROM/RAM/UART
 board is installed, the monitor will most likely reside in that ROM.
 
 2)  Target monitor RAM location, RAM_START.  The monitors require
 approximately 300 bytes of RAM; less if the stack sizes can be reduced, or
 if a smaller communications buffer is acceptable.  The communications
 buffer size, COMBUF_SIZE, must be at least 19 bytes.  Monitor RAM should
 be located such that it does not inconvenience the project being
 developed.  If a ROM/RAM/UART board is installed, it may be convenient to
 use the top or bottom of the RAM on that board.
 
 3)  Target hardware initialization.  This is the most involved portion of
 porting the monitor.  If the target processor is a single-chip micro with
 onboard peripherals, the prototype target monitor will probably contain
 most of the initialization code already.  In any case, the initialization
 code developed here will likely be reused in the startup code for the
 final product.
 
 4)  Target UART.  The UART to be used for target communications must be
 initialized, and the basic transmit and receive routines written.  If a
 ROM/RAM/UART board is installed, that board's UART will most likely be
 used.  Code for such a UART, as well as for any UART on the microprocessor
 chip itself, may exist in the prototype target monitor.
 
 5)  Breakpoint Instruction.  If the target processor has a single-byte
 software interrupt instruction, it is convenient to use it as the
 breakpoint instruction, as a single byte breakpoint may be placed at any
 desired RAM location.  However, if the target has no such instruction, or
 if the instruction is being used by the application code, or if the
 monitor does not have access to the interrupt vector for the instruction
 (as may occur during testing of the target monitor under another debug
 monitor), then a multi-byte breakpoint instruction may be used.
 Typically, the multi-byte breakpoint instruction will be a call to a
 monitor subroutine, which will push processor registers so as to simulate
 an interrupt.  In most cases, the prototype target monitor will have
 appropriate code for the breakpoint instruction.


16.1  Testing a Customized Target

 Test the modified target monitor by connecting its serial port to that of
 a PC.  Turn on the target, and then run NoICE.  Use the SHOW=1 command
 line option of NoICE to display the hex values of communications to and
 from the target.  When NoICE starts up, it first attempts to read the
 target version and status information (see FN_GET_STATUS in section 15).
 If this is successful, NoICE then attempts to read the target registers
 (see FN_READ_REGS in section 15).  If this is successful, NoICE then
 attempts to read memory locations to refresh the disassembler window (see
 FN_READ_MEM in section 15).
 
 Three tries are made for each function.  If any function fails to respond
 after three attempts, the operator is informed.
 
 The hex values (if any) displayed by SHOW=1 can assist you in debugging
 your target monitor.  The most common problems are bad cables and
 mismatched baud rates (unless, of course, you happen to make a programming
 error...).
 
 Most of the communications functions can be exercised individually via
 keyboard commands:
 
 VER or F9 will exercise FN_GET_STATUS, and display any results, including
 the target's identification string.
 
 R followed by carriage return will exercise FN_READ_REGS.  Any returned
 values will be displayed in the register window.  A common error is to
 forget to return 16 bit registers least significant byte first.  Check the
 displayed stack pointer to see if this is the case.
 
 R followed by a register name and a value will exercise FN_WRITE_REGS.  In
 order to verify that the register was accepted by the target, follow this
 command by R to read back the registers from the target.
 
 M followed by an address will exercise FN_READ_MEM to read one byte at the
 specified address.  It is often useful to read the first byte of the
 target monitor, or some other location with known contents. DUMP or UNASM
 will use FN_READ_MEM to read multiple bytes.
 
 M followed by an address and a value or values will exerciese FN_WRITE_MEM
 to write the specied values to the specified address.  Since FN_WRITE_MEM
 verifies the write, you should attempt to write both RAM and PROM in order
 to insure that the monitor verifies correctly.
 
 IN followed by an address will exercise FN_IN to input a byte from the
 specified address.  This should be tested even if your target does not
 have specific I/O instructions.
 
 OUT followed by an address and a value will exercise FN_OUT to output a
 byte to the specified address.  This should be tested even if your target
 does not have specific I/O instructions.
 
 B followed by an address will exercise FN_SET_BYTE twice, to temporarily
 insert and remove a breakpoint.  In order to test the ability to set
 multiple bytes with a single FN_SET_BYTE, you must set several
 breakpoints, and then issue a GO command to insert them all.
 
 GO will exercise FN_RUN_TARGET.  If an address is specifed, it will be
 sent to the target via FN_WRITE_REGS before FN_RUN_TARGET is issued.  If
 breakpoints have been set, they will be sent to the target via
 FN_SET_BYTES before FN_RUN_TARGET is issued.  A reply to FN_RUN_TARGET
 will only occur if the target returns to the monitor after beginning
 execution.  This may be arranged either by inserting a breakpoint, or by
 assembling a breakpoint instruction (typically a software interrupt) into
 the code to be executed on the target.


17.  TWO BIT MEMORY MANAGEMENT

 Eight bit processors can do a remarkable amount of work, but sometimes a
 16 bit address space just isn't enough.  We have had considerable success
 with a simple scheme which bank switches a portion of system ROM.  RAM is
 generally not banked, although there is no reason why this technique would
 not work for RAM as well, or instead of, ROM.
 
 Consider a Z80 processor with 32K of RAM between 8000h and 0FFFFh (A15=1);
 and 32K of ROM from between 0000h and 7FFFh (A15=0).  Let the 16K of ROM
 between 0000h and 3FFFh be always mapped.  It contains the restart and
 interrupt vectors, the interrupt handlers, shared subroutines, and other
 "root" code.  Let the 16K of ROM between 4000h and 7FFFh be mapped to one
 of eight pages, with the page number selected by a three bit latch
 somewhere in the processor's I/O space.
 
 Rules of use are the classic rules for overlays.  The root can call
 subroutines in the root, or it can map to and call subroutines in the
 overlays.  An overlay can call subroutine within itself, or in the root,
 but cannot call subroutines in other overlays.  (If necessary, more
 complex software can be written to save overlay information on the stack
 and allow inter-overlay calls, but this is seldom necessary.)
 
 The hardware is pitifully simple:  in addition to the 3 bit page latch, it
 requires 3 two input AND gates and a 128 Kbyte ROM.
 
                     +--------+
    A15 -------------|        |
                     |   AND  |------ ROM /CS
    /MREQ -----------|        |
                     +--------+
                     +--------+
    A14 -------------|        |
                     |   AND  |------ ROM A16
    latched PG2------|        |
                     +--------+
                     +--------+
       A14 ----------|        |
                     |   AND  |------ ROM A15
    latched PG1------|        |
                     +--------+
                     +--------+
       A14 ----------|        |
                     |   AND  |------ ROM A14
    latched PG0------|        |
                     +--------+
    A13 ----------------------------- ROM A13
                          ...
    A0  ----------------------------- ROM A0
 
 When processor A15=1 or /MREQ=1 (/MREQ is the Z80's low true memory
 request), the ROM is deselected.  When A15=0 and /MREQ=0, the ROM is
 selected, and one of eight 16K pages is accessed, depending on the values
 on ROM A14, A15, and A16.  When processor A14=0, the outputs of the AND
 gates will be zero regardless of the value in the page latch (PG2, PG1,
 PG0).  Thus, the root page is selected.  When processor A15=0, /MREQ=0,
 and A14=1, the contents of the page latch is applied to ROM A14, A15, and
 A16, selecting one of eight pages.  As page 000 is the root, there are
 effectively seven useful overlay pages.
 
 The same circuit works for top-end-ROM processors such as the 68HC11
 simply by replacing the AND gates in the above circuit with OR gates.
 Obviously, more or fewer latched page bits may be used to select more or
 fewer pages.


18.  BUGS, FEATURES, ORDERING INFORMATION

 If you use NoICE, but have not yet registered this copy, please do so now.
 The cost is $25 (US) for the first processor, and $5 (US) for each
 additional processor ordered at the same time.  Send your check to:
 
        John Hartman
        1030 14th Avenue Southeast
        Minneapolis, MN 55414
 
 Software will be shipped on a 720K 3.5 inch floppy unless your order
 specifies 1.2M 5.25 inch floppy.  Be sure to specify the desired target
 processor(s).
 
 The distribution package includes
    -   NoICExxx PC-host program and on-line help
    -   Printed User's Guide
    -   Target assembly language source code for MONxxx target monitor
    -   Executables and C source code for all symbol processing utilities
        described in section 12.
 
 If you find a bug, or would like to suggest an enhancement, please contact
 me at the above address.
 
 Disclaimer:
 
 NoICE is distributed as is, with no guarantee that it will work correctly
 in all situations.  In no event will the Author be liable for any damages,
 including lost profits, lost savings or other incidental or consequential
 damages arising out of the use of or inability to use these programs, even
 if the Author has been advised of the possibility of such damages, or for
 any claim by any other party.
 
 Copyright Information:
 
 The entire NoICE distribution package, consisting of the main program,
 documentation files, and various data and utility files, is copyright (c)
 1993, by John Hartman.
 
 The author reserves the exclusive right to distribute this package, or any
 part thereof, for profit.
 
 The Z80 version of NoICE (NOICEZ80) and various subsidiary files may be
 copied freely by individuals for non-commercial purposes.  All other
 versions may only be distributed by the author.
 
 ONLY UNMODIFIED VERSIONS DISPLAYING THE AUTHOR'S COPYRIGHT MAY BE COPIED.
 
 User groups and clubs are authorized to distribute NOICEZ80 under the
 following conditions:
 
 1.  No charge is made for the software or documentation.  A nominal
 distribution fee may be charged, provided that it is no more than $10
 total.
 
 3.  The program and documentation are not modified in ANY way, and are
 distributed together.
